backend/src/downloader/universal-status.ts (3)

Line range hint 26-44: Improve error handling and consider async operations.

The current implementation has several areas for improvement:

1. Silent error handling could mask important issues
2. Synchronous file operations could block the event loop
3. Missing validation of the loaded data structure

-  private loadStatus() {
+  private async loadStatus() {
     try {
-      const file = fs.readFileSync(this.statusPath, 'utf-8');
+      const file = await fs.promises.readFile(this.statusPath, 'utf-8');
       const data = JSON.parse(file);
+      // Validate data structure
+      if (!this.isValidStatusData(data)) {
+        throw new Error('Invalid status data structure');
+      }
       this.status = Object.entries(data).reduce(
         (acc, [key, value]: [string, any]) => {
           acc[key] = {
             ...value,
             lastChecked: value.lastChecked
               ? new Date(value.lastChecked)
               : new Date(),
           };
           return acc;
         },
         {} as Record<string, UniversalStatus>,
       );
     } catch (error) {
+      console.warn(`Failed to load status: ${error.message}`);
       this.status = {};
     }
   }

---

Line range hint 45-54: Convert file operations to async/await pattern.

The synchronous file operations should be converted to asynchronous to prevent blocking the event loop.

-  private saveStatus() {
+  private async saveStatus() {
     const statusDir = path.dirname(this.statusPath);
-    if (!fs.existsSync(statusDir)) {
-      fs.mkdirSync(statusDir, { recursive: true });
+    try {
+      await fs.promises.mkdir(statusDir, { recursive: true });
+      await fs.promises.writeFile(
+        this.statusPath,
+        JSON.stringify(this.status, null, 2),
+        'utf-8'
+      );
+    } catch (error) {
+      console.error(`Failed to save status: ${error.message}`);
+      throw error;
     }
-    fs.writeFileSync(
-      this.statusPath,
-      JSON.stringify(this.status, null, 2),
-      'utf-8'
-    );
   }

---

Line range hint 56-71: Fix parameter naming and improve object copying.

1. The parameter UniversalName should follow camelCase convention
2. Consider using deep copy for getAllStatus to prevent mutation of nested objects

-  updateStatus(UniversalName: string, isDownloaded: boolean) {
+  updateStatus(universalName: string, isDownloaded: boolean) {
-    this.status[UniversalName] = {
+    this.status[universalName] = {
       isDownloaded,
       lastChecked: new Date(),
     };
     this.saveStatus();
   }

-  getStatus(UniversalName: string): UniversalStatus | undefined {
-    return this.status[UniversalName];
+  getStatus(universalName: string): UniversalStatus | undefined {
+    const status = this.status[universalName];
+    return status ? { ...status, lastChecked: new Date(status.lastChecked) } : undefined;
   }

   getAllStatus(): Record<string, UniversalStatus> {
-    return { ...this.status };
+    return Object.entries(this.status).reduce((acc, [key, value]) => {
+      acc[key] = { ...value, lastChecked: new Date(value.lastChecked) };
+      return acc;
+    }, {} as Record<string, UniversalStatus>);
   }

backend/src/embedding/local-embedding-provider.ts (1)

Line range hint 5-27: Convert class with static members to module with functions.

The class contains only static members, which is an anti-pattern. Consider converting it to a module with exported functions.

-export class EmbeddingProvider {
-  private static logger = new Logger(EmbeddingProvider.name);
+const logger = new Logger('EmbeddingProvider');
 
-  static async generateEmbResponse(model: string, message: string[]) {
+export async function generateEmbResponse(model: string, message: string[]) {
     const embLoader = EmbeddingDownloader.getInstance();
     try {
       const embeddingModel = await embLoader.getPipeline(model);
       const embeddings = embeddingModel.embed(message);
 
       for await (const batch of embeddings) {
-        console.log(batch);
+        logger.debug(batch);
       }
     } catch (error) {
-      this.logger.log(`error when using ${model} api`);
+      logger.error(`Error when using ${model} api: ${error.message}`, error.stack);
+      throw error;
     }
   }
 
-  static async getEmbList() {
+export async function getEmbList() {
     Object.values(EmbeddingModel).forEach((model) => {
-      this.logger.log(model);
+      logger.log(model);
     });
   }
-}

backend/src/main.ts (3)

25-27: Improve port configuration logging.

Consider these improvements:

1. Use the Logger instead of console.log for consistency
2. Extract the port number to a constant to avoid repetition

+  const port = process.env.PORT ?? 8080;
-  console.log('process.env.PORT:', process.env.PORT);
+  logger.debug(`Configured PORT: ${process.env.PORT}`);
-  const server = await app.listen(process.env.PORT ?? 8080);
+  const server = await app.listen(port);
-  logger.log(`Application is running on port ${process.env.PORT ?? 8080}`);
+  logger.log(`Application is running on port ${port}`);

---

29-45: Consider adding a shutdown timeout.

The graceful shutdown implementation is good, but it might hang indefinitely if the shutdown process gets stuck. Consider adding a timeout to force exit after a reasonable duration.

   process.on(signal, async () => {
     logger.log(`Received ${signal} signal. Starting graceful shutdown...`);
 
+    // Force exit after 10 seconds
+    const shutdownTimeout = setTimeout(() => {
+      logger.error('Forced shutdown due to timeout');
+      process.exit(1);
+    }, 10000);
+
     try {
       await app.close();
       await server.close();
       logger.log('Server closed successfully');
+      clearTimeout(shutdownTimeout);
       process.exit(0);
     } catch (error) {
       logger.error('Error during graceful shutdown:', error);
+      clearTimeout(shutdownTimeout);
       process.exit(1);
     }
   });

---

48-51: Enhance bootstrap error handling.

The error handling could be improved by:

1. Using the Logger instead of console.error
2. Providing more specific error context

+const logger = new Logger('Bootstrap');
-bootstrap().catch((error) => {
-  console.error('Fatal error during application startup:', error);
+bootstrap().catch((error: Error) => {
+  logger.error('Failed to start application', {
+    error: error.message,
+    stack: error.stack,
+  });
   process.exit(1);
 });

backend/src/downloader/universal-status.ts (1)

Line range hint 10-24: Consider adding thread-safety to the singleton implementation.

While the singleton pattern is correctly implemented, in a Node.js environment with potential concurrent access, consider using a double-checked locking pattern or ensuring atomicity of instance creation.

 public static getInstance(): UniversalStatusManager {
+  // Double-checked locking pattern
+  if (!UniversalStatusManager.instance) {
+    // In production, consider using a proper mutex/lock mechanism
+    const tempInstance = new UniversalStatusManager();
+    UniversalStatusManager.instance = tempInstance;
+  }
-  if (!UniversalStatusManager.instance) {
-    UniversalStatusManager.instance = new UniversalStatusManager();
-  }
   return UniversalStatusManager.instance;
 }

llm-server/src/model/remote-model-instance.ts (3)

43-64: Ensure proper error stack trace preservation

When creating a new ModelError, consider preserving the original error's stack trace to aid in debugging and troubleshooting.

Apply this diff to include the original error stack trace:

   private createModelError(error: unknown): ModelError {
     const modelError = new Error('Model error occurred') as ModelError;

+    if (error instanceof Error && error.stack) {
+      modelError.stack = error.stack;
+    }
     
     if (error instanceof OpenAI.APIError) {
       modelError.message = error.message;
       modelError.code = String(error.status) || 'OPENAI_API_ERROR';
       modelError.retryable = [429, 503, 502].includes(error.status);
       modelError.details = error.error;

---

82-83: Avoid logging sensitive error details in chat

Logging the entire modelError object may expose sensitive information. It's safer to log only the error message.

Apply this diff to adjust the logging statement:

         this.logger.error('Error in chat:', modelError);
+        this.logger.error(`Error in chat: ${modelError.message}`);

---

112-113: Avoid logging sensitive error details in chatStream

Similar to the chat method, ensure that logging in chatStream does not expose sensitive details by logging only the error message.

Apply this diff to adjust the logging statement:

         this.logger.error('Error in chatStream:', modelError);
+        this.logger.error(`Error in chatStream: ${modelError.message}`);

llm-server/src/llm-provider.ts (2)

74-79: Consider aggregating initialization errors

When a model fails to initialize, the error is logged, but the process continues. Consider collecting all initialization errors and reporting them after attempting to initialize all models to provide a consolidated view of any issues.

---

155-158: Ensure error responses are sent when streaming

In generateStreamingResponse, if an error occurs after headers are sent, ensure an error response is properly streamed back to the client to prevent hanging connections.

Apply this diff to send an error message in the stream:

       if (!res.writableEnded) {
         this.logger.error('Error in streaming response:', error);
+        const errorResponse = {
+          error: {
+            message: error.message || 'Unknown error occurred',
+            code: error.code || 'UNKNOWN_ERROR',
+            details: error.details || error,
+          },
+        };
+        res.write(`data: ${JSON.stringify(errorResponse)}\n\n`);
+        res.write('data: [DONE]\n\n');
         res.end();
       }

codefox-common/src/config-loader.ts (2)

130-140: Add error handling in saveConfig() to manage write failures

The saveConfig() method doesn't handle potential errors that might occur during file writing operations. It's important to handle exceptions to prevent the application from crashing unexpectedly.

Modify the method to include a try-catch block:

private saveConfig() {
  const configDir = path.dirname(this.configPath);
  if (!fs.existsSync(configDir)) {
    fs.mkdirSync(configDir, { recursive: true });
  }
  try {
    fs.writeFileSync(
      this.configPath,
      JSON.stringify(this.config, null, 2),
      'utf-8'
    );
  } catch (error) {
    this.logger.error('Failed to save configuration:', error);
    // Handle the error as appropriate (e.g., rethrow, alert the user, etc.)
  }
}

---

241-241: Standardize comments to English for consistency

The comment on line 241 is in Chinese. For consistency and maintainability, all code comments should be in English.

Apply this diff to translate the comment:

- // 验证 chat 模型配置
+ // Validate chat model configurations

Review the codebase for other non-English comments and update them accordingly.

llm-server/src/main.ts (3)

11-24: Reconsider exiting the process on uncaught exceptions and unhandled rejections

Immediately exiting the process upon an uncaught exception or unhandled rejection might cause service interruptions. Consider implementing a more graceful error handling strategy, such as logging the error and allowing the server to continue running or using a process manager to handle restarts.

---

95-97: Clarify the purpose of '/tags' and '/models' routes

Both /tags and /models routes are handled by handleModelTagsRequest. If they serve the same purpose, consider removing one to avoid redundancy. If they are intended for different functionalities, separate the route handlers accordingly.

---

11-24: Avoid redundant logging of stack traces

Stack traces are logged using both console.error and this.logger.error. This duplication can clutter logs and make them harder to read. Prefer using this.logger for consistent logging practices.

Simplify the logging statements by using the logger exclusively.

backend/src/build-system/context.ts (1)

15-15: Consider using an abstraction for the model provider to enhance flexibility

By directly referencing and instantiating OpenAIModelProvider, the BuilderContext class becomes tightly coupled to this specific implementation. To improve flexibility and facilitate potential future changes or testing, consider using an interface or abstract class to represent the model provider. This way, different implementations can be swapped in without modifying the BuilderContext class.

For example, you could define an interface IModelProvider and have OpenAIModelProvider implement it:

// Define the interface
export interface IModelProvider {
  // Define the methods and properties required
}

// Implement the interface in OpenAIModelProvider
export class OpenAIModelProvider implements IModelProvider {
  // Implementation details
}

// Use the interface in BuilderContext
public model: IModelProvider;

// Instantiate with a concrete implementation
this.model = OpenAIModelProvider.getInstance();

Also applies to: 63-63, 72-72

backend/src/build-system/project-builder.service.ts (1)

9-9: Rename models to model for clarity

The variable models holds a single instance of OpenAIModelProvider, suggesting it represents a single model provider rather than multiple models. Renaming it to model or modelProvider can improve code readability and accurately reflect its purpose.

Apply this diff to rename the variable:

- private models: OpenAIModelProvider = OpenAIModelProvider.getInstance();
+ private model: OpenAIModelProvider = OpenAIModelProvider.getInstance();

backend/src/common/interfaces/entity.interfaces.ts (3)

8-8: Specify a more precise type for roles in IUser

Currently, roles is typed as any[], which may lead to type safety issues. Consider defining an enum or a specific type for user roles to improve type safety and maintainability.

For example:

export enum UserRole {
  Admin = 'Admin',
  User = 'User',
  Guest = 'Guest',
  // Add other roles as needed
}

export interface IUser {
  id: string;
  username: string;
  email: string;
  chats?: IChat[];
  roles?: UserRole[];
}

---

17-21: Ensure consistency of optional fields across interfaces

In IChat, properties like isActive, isDeleted, createdAt, and updatedAt are optional, whereas in IMessage, these properties are required. For consistency and to prevent potential null or undefined errors, consider making these properties either optional or required in both interfaces, depending on your application's requirements.

For instance, if these properties should always be present:

// In IChat interface
- isActive?: boolean;
- isDeleted?: boolean;
- createdAt?: Date;
- updatedAt?: Date;
+ isActive: boolean;
+ isDeleted: boolean;
+ createdAt: Date;
+ updatedAt: Date;

Or, if they can be undefined:

// In IMessage interface
- isActive: boolean;
- isDeleted: boolean;
- createdAt: Date;
- updatedAt: Date;
+ isActive?: boolean;
+ isDeleted?: boolean;
+ createdAt?: Date;
+ updatedAt?: Date;

Also applies to: 27-31

---

23-31: Add chatId to IMessage to associate messages with their chats

Including a chatId property in the IMessage interface can explicitly link each message to its parent chat, facilitating operations like querying messages by chat and ensuring data integrity.

Example:

export interface IMessage {
  id: string;
  content: string;
  role: MessageRole;
  chatId: string;
  createdAt: Date;
  updatedAt: Date;
  isActive: boolean;
  isDeleted: boolean;
}

codefox-common/jest.config.js (2)

18-19: Consider adding coverage thresholds.

Adding coverage thresholds helps maintain code quality by enforcing minimum test coverage requirements.

 collectCoverageFrom: ['**/*.(t|j)s'],
 coverageDirectory: '../coverage',
+coverageThreshold: {
+  global: {
+    branches: 80,
+    functions: 80,
+    lines: 80,
+    statements: 80
+  }
+},

---

24-24: Consider making transformIgnorePatterns more specific.

The current pattern might transform more node_modules than necessary. Consider listing specific packages that need transformation.

-transformIgnorePatterns: ['node_modules/(?!(strip-json-comments)/)'],
+transformIgnorePatterns: [
+  'node_modules/(?!(' +
+    'strip-json-comments' +
+    ')/)',
+],

codefox-common/src/model-api.ts (1)

3-20: Add JSDoc comments to exported types.

Consider adding JSDoc comments to document the purpose and usage of each exported type. This will improve code maintainability and IDE support.

 // Core types from OpenAI API
+/** Message parameter for OpenAI Chat API */
 export type ModelApiMessage = OpenAI.Chat.ChatCompletionMessageParam;
+/** Request parameters for creating a chat completion */
 export type ModelApiRequest = OpenAI.Chat.ChatCompletionCreateParams;
+/** Response from the chat completion API */
 export type ModelApiResponse = OpenAI.Chat.ChatCompletion;
+/** Chunk of streaming response from the chat completion API */
 export type ModelApiStreamChunk = OpenAI.Chat.ChatCompletionChunk;

 // Additional useful types
+/** Role of the message sender (system, user, assistant) */
 export type ModelApiRole = OpenAI.Chat.ChatCompletionRole;
+/** Function definition for chat completion */
 export type ModelApiFunction = OpenAI.Chat.ChatCompletionCreateParams.Function;
+/** Function call details in chat completion */
 export type ModelApiFunctionCall =
   OpenAI.Chat.ChatCompletionMessage.FunctionCall;

 // Error types
+/** OpenAI API error instance */
 export type ModelApiError = InstanceType<typeof OpenAI.APIError>;
+/** Specific error codes that can be returned by the API */
 export type ModelApiErrorCode =
   | 'rate_limit_exceeded'
   | 'invalid_request_error'
   | 'api_error';

llm-server/jest.config.js (1)

28-33: Remove redundant TypeScript configuration

The ts-jest configuration in globals duplicates the settings already specified in the transform section. Consider removing the redundant configuration to maintain a single source of truth.

-  globals: {
-    'ts-jest': {
-      useESM: true,
-      tsconfig: 'tsconfig.test.json',
-    },
-  },

llm-server/.eslintrc.cjs (1)

18-24: Consider adding test files to ignorePatterns

The ignore patterns could be expanded to include test files to prevent linting conflicts.

  ignorePatterns: [
    '.eslintrc.cjs',
    'jest.config.js',
    'dist',
    'node_modules',
    'coverage',
+   '**/*.spec.ts',
+   '**/*.test.ts',
  ],

backend/src/common/model-provider/types.ts (1)

1-2: Consider consolidating ChatCompletionChunk imports.

You're importing ChatCompletionChunk from both OpenAI and your local model. Consider using a type alias if these types are identical to avoid confusion.

llm-server/src/downloader/const.ts (1)

1-70: Remove duplicate entries and consider organizing models.

1. Remove duplicate entries:

   • 'claude-2.0' appears twice (lines 15 and 37)
   • 'claude-instant-1.2' appears twice (lines 16 and 40)

2. Consider organizing models by provider or capability for better maintainability.

 export const REMOTE_MODEL_LISTS = [
+  // OpenAI Models
   'gpt-4-0125-preview',
   'gpt-4-1106-preview',
   'gpt-4-vision-preview',
   // ... other GPT models
+  // Anthropic Models
   'claude-3-opus-20240229',
   // ... other Claude models
-  'claude-2.0',  // Remove duplicate
-  'claude-instant-1.2',  // Remove duplicate
   // ... rest of the models
 ];

backend/src/build-system/handlers/database/requirements-document/index.ts (1)

6-6: LGTM! Model provider transition looks good.

The change from ModelProvider singleton to context-based model injection improves dependency management and testability.

This architectural change:

• Reduces global state dependencies
• Makes testing easier through dependency injection
• Aligns with the single responsibility principle

Also applies to: 18-18

backend/src/downloader/universal-utils.ts (1)

14-14: Standardize logging approach.

Mixed usage of console.log and logger creates inconsistency. Stick to the Logger service throughout.

-  console.log('Embedding load starts');
+  logger.log('Embedding load starts');
   await checkAndDownloadAllEmbeddings();
-  console.log('Embedding load ends');
+  logger.log('Embedding load ends');
   // ... later in the file ...
-  console.log('Embedding load finished');
+  logger.log('Embedding load finished');

Also applies to: 16-16, 29-29

llm-server/src/downloader/model-downloader.ts (1)

Line range hint 27-28: Remove debug console.log statement.

Debug logging should use the Logger service or be removed.

-      console.log(this.statusManager);

llm-server/src/downloader/universal-status.ts (2)

27-46: Enhance error handling in loadStatus method.

The catch-all error handling could mask specific issues. Consider handling different types of errors separately (e.g., file not found vs. invalid JSON).

 private loadStatus() {
   try {
     const file = fs.readFileSync(this.statusPath, 'utf-8');
     const data = JSON.parse(file);
     this.status = Object.entries(data).reduce(
       (acc, [key, value]: [string, any]) => {
         acc[key] = {
           ...value,
           lastChecked: value.lastChecked
             ? new Date(value.lastChecked)
             : new Date(),
         };
         return acc;
       },
       {} as Record<string, UniversalStatus>,
     );
   } catch (error) {
-    this.status = {};
+    if (error instanceof SyntaxError) {
+      this.logger.error('Invalid JSON in status file:', error);
+      this.status = {};
+    } else if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      this.logger.debug('Status file not found, initializing empty status');
+      this.status = {};
+    } else {
+      this.logger.error('Unexpected error loading status:', error);
+      this.status = {};
+    }
   }
 }

---

32-32: Improve type safety in reduce callback.

The any type in the reduce callback could be replaced with a more specific type.

-        (acc, [key, value]: [string, any]) => {
+        (acc, [key, value]: [string, Partial<UniversalStatus>]) => {

llm-server/src/downloader/universal-utils.ts (2)

53-53: Address the TODO comment.

The comment indicates a need for workflow refactoring. I can help implement this improvement.

Would you like me to help design and implement the refactored workflow? I can create a GitHub issue to track this task.

---

59-62: Consider adding concurrency control.

The current implementation downloads all models simultaneously, which could lead to memory issues with a large number of models.

Consider using a concurrency limit:

+ import pLimit from 'p-limit';
+
+ const limit = pLimit(3); // limit concurrent downloads
  const downloadTasks = modelsConfig.map(async config => {
    const { model, task } = config;
-   await downloadModel(model, task);
+   return limit(() => downloadModel(model, task));
  });

backend/src/build-system/__tests__/test.sms-lvl2.spec.ts (1)

5-83: Consider enhancing test coverage.

While the happy path is tested, consider adding:

1. Error cases (invalid sequence, missing dependencies)
2. Edge cases (empty steps, circular dependencies)
3. Performance benchmarks for the 300s timeout

Also, consider breaking down the sequence definition into a separate fixture file for better maintainability.

backend/src/build-system/handlers/ux/sitemap-structure/sms-page.ts (1)

67-67: Address TODO comment regarding platform parameter.

The platform is hardcoded as 'web'. This TODO should be addressed by implementing dynamic platform detection or making it configurable.

Would you like me to help implement the dynamic platform detection or create an issue to track this?

llm-server/tsconfig.json (1)

19-21: Consider more specific path mappings.

The current path mapping "*": ["node_modules/*"] is very broad. Consider being more specific about which modules need path mapping to avoid potential resolution conflicts.

     "paths": {
-      "*": ["node_modules/*"]
+      "@codefox/*": ["packages/*/src"]
     },

package.json (1)

Line range hint 24-29: Consider using exact versions for development dependencies.

Using ^ in version numbers can lead to unexpected updates. For development dependencies, it's often safer to use exact versions to ensure consistent behavior across all environments.

   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "eslint": "^8.57.1",
-    "eslint-config-prettier": "^9.0.0",
-    "prettier": "^3.0.0",
+    "@typescript-eslint/eslint-plugin": "8.0.0",
+    "@typescript-eslint/parser": "8.0.0",
+    "eslint": "8.57.1",
+    "eslint-config-prettier": "9.0.0",
+    "prettier": "3.0.0",

config.schema.json (2)

7-46: Add additional validations for chat models configuration.

Consider adding these validations to improve schema robustness:

1. Add maxItems to limit the number of chat models
2. Add pattern validation for token similar to embedding models
3. Add validation to ensure only one default model exists

   "chat": {
     "type": "array",
     "description": "Chat models configuration",
+    "maxItems": 10,
     "items": {
       "type": "object",
       "required": ["model"],
       "properties": {
         "model": {
           "type": "string",
           "description": "Model name (e.g. gpt-4 for OpenAI API, or llama2 for local model)",
           "examples": ["gpt-4", "gpt-3.5-turbo", "llama2"]
         },
         "token": {
           "type": "string",
-          "description": "API authentication token"
+          "description": "API authentication token",
+          "pattern": "^sk-[a-zA-Z0-9]+$"
         }
       }
     }
   }

---

47-82: Add validation for default embedding model.

Consider adding a validation to ensure only one embedding model can be set as default.

   "embedding": {
     "type": "array",
     "description": "Embedding models configuration",
+    "maxItems": 5,
+    "oneDefault": {
+      "properties": ["default"],
+      "maximum": 1
+    },
     "items": {
       // ... existing configuration
     }
   }

README.md (1)

83-88: Add language specification to code block.

To fix the markdown linting issue, specify the language for the code block.

-```
+```text
 codefox/
 ├── backend/         # NestJS backend server
 ├── frontend/        # Next.js frontend application
 └── llm-server/     # LLM service

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 Markdownlint (0.37.0)</summary>

83-83: null
Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

</blockquote></details>
<details>
<summary>codefox-common/README.md (4)</summary><blockquote>

`7-24`: **Enhance installation instructions for clarity.**

Consider adding:
1. A brief explanation of what "workspace package" means
2. A note about pnpm being the required package manager
3. A link to pnpm's documentation for those unfamiliar with it


```diff
 Since this is a workspace package, you can add it to your project's dependencies:
+
+> Note: This package is part of a pnpm workspace, which allows local packages to reference each other. Make sure you have [pnpm](https://pnpm.io/) installed.

---

57-82: Enhance type definitions with documentation and examples.

Consider these improvements to make the types more maintainable and user-friendly:

 // Base entity with common fields
 interface BaseEntity {
+  /** Unique identifier for the entity */
   id: string;
+  /** Timestamp when the entity was created */
   createdAt: Date;
+  /** Timestamp when the entity was last updated */
   updatedAt: Date;
 }

 // Error response structure
 interface ErrorResponse {
+  /** Error code for categorizing the error */
   code: string;
+  /** Human-readable error message */
   message: string;
+  /** Additional error context
+   * @example
+   * {
+   *   field: "email",
+   *   constraint: "must be unique"
+   * }
+   */
-  details?: Record<string, unknown>;
+  details?: Record<string, string | number | boolean>;
 }

 // Generic result type
+/** Represents either a successful operation with data or a failed operation with error details
+ * @example
+ * // Success case
+ * const success: Result<User> = {
+ *   success: true,
+ *   data: { id: '1', name: 'John' }
+ * };
+ * 
+ * // Error case
+ * const error: Result<User> = {
+ *   success: false,
+ *   error: { code: 'NOT_FOUND', message: 'User not found' }
+ * };
+ */
 type Result<T> =

---

93-103: Add language specifier to the fenced code block.

To comply with markdown best practices and improve syntax highlighting:

-```
+```text
 codefox-common/
 ├── src/

🧰 Tools

🪛 Markdownlint (0.37.0)

93-93: null
Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

113-113: Consider adding contributing and testing sections.

To make the documentation more comprehensive, consider adding:

1. Contributing guidelines
2. Testing instructions (if applicable)
3. License information

Would you like me to help draft these additional sections?

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro